home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / cat3 / standard / ldopen.z / ldopen
Encoding:
Text File  |  2002-10-03  |  6.2 KB  |  111 lines
  1. LDOPEN(3X)                                             Last changed: 1-8-99
  2.  
  3.  
  4. NNAAMMEE
  5.      llddooppeenn, llddaaooppeenn - Opens a common object file for reading
  6.  
  7. SSYYNNOOPPSSIISS
  8.      ##iinncclluuddee <<ssttddiioo..hh>>
  9.      ##iinncclluuddee <<ffiilleehhddrr..hh>>
  10.      ##iinncclluuddee <<ssyymmss..hh>>
  11.      ##iinncclluuddee <<llddffccnn..hh>>
  12.  
  13.      LLDDFFIILLEE **llddooppeenn (("_f_i_l_e_n_a_m_e,,llddppttrr""))
  14.      cchhaarr **_f_i_l_e_n_a_me;;
  15.      LLDDFFIILLEE **_l_d_p_t_r;;
  16.  
  17.      LLDDFFIILLEE **llddaaooppeenn (("_f_i_l_e_n_a_m_e,,oollddppttrr""))
  18.      cchhaarr **_f_i_l_e_n_a_m_e;;
  19.      LLDDFFIILLEE **_o_l_d_p_t_r;;
  20.  
  21.      iinntt llddrreeaaddsstt (("_l_d_p_t_r,,ffllaaggss""))
  22.      LLDDFFIILLEE **_l_d_p_t_r;;
  23.      iinntt _f_l_a_g_s;
  24.  
  25. IIMMPPLLEEMMEENNTTAATTIIOONN
  26.      IRIX systems (o32 ABI only)
  27.  
  28. DDEESSCCRRIIPPTTIIOONN
  29.      llddooppeenn and llddcclloossee(3X) provide uniform access to simple object files
  30.      and to object files that are members of archive files.  An archive of
  31.      common object files can be processed as if it were a series of simple
  32.      common object files.
  33.  
  34.      If _l_d_p_t_r has the value NNUULLLL, llddooppeenn opens _f_i_l_e_n_a_m_e, allocates and
  35.      initializes the LLDDFFIILLEE structure, and returns a pointer to the
  36.      structure to the calling program.
  37.  
  38.      If _l_d_p_t_r is valid and TTYYPPEE((_l_d_p_t_r)) is the archive magic number, llddooppeenn
  39.      reinitializes the LLDDFFIILLEE structure for the next archive member of
  40.      _f_i_l_e_n_a_m_e.
  41.  
  42.      llddooppeenn and llddcclloossee work in concert.  llddcclloossee returns FFAAIILLUURREE only when
  43.      TTYYPPEE((_l_d_p_t_r)) is the archive magic number and there is another file in
  44.      the archive to be processed.  Only then should llddooppeenn be called with
  45.      the current value of _l_d_p_t_r.  In all other cases, and particularly when
  46.      a new _f_i_l_e_n_a_m_e is opened, llddooppeenn should be called with a NNUULLLL _l_d_p_t_r
  47.      argument.
  48.  
  49.      The following is a prototype for the use of llddooppeenn and llddcclloossee.  It
  50.      handles individual object (or aa..oouutt) files and (via the wwhhiillee--lloooopp) an
  51.      archive file [see aarr(1)] of object files.
  52.  
  53.           /* for each filename to be processed */
  54.  
  55.           ldptr = NULL;
  56.           do  {
  57.                if ( (ldptr = ldopen(filename, ldptr)) != NULL )
  58.                {
  59.                     /* check magic number */
  60.                     /* process a single object file */
  61.                }
  62.           } while (ldclose(ldptr) == FAILURE );
  63.  
  64.      If the value of _o_l_d_p_t_r is not NNUULLLL, llddaaooppeenn opens _f_i_l_e_n_a_m_e anew and
  65.      allocates and initializes a new LLDDFFIILLEE structure, copying the fields
  66.      from _o_l_d_p_t_r.  llddaaooppeenn returns a pointer to the new LLDDFFIILLEE structure.
  67.      This new pointer is independent of the old pointer, _o_l_d_p_t_r.  The two
  68.      pointers can be used concurrently to read separate parts of the object
  69.      file.  For example, one pointer can be used to step sequentially
  70.      through the relocation information while the other is used to read
  71.      indexed symbol table entries.
  72.  
  73.      llddooppeenn and llddaaooppeenn open _f_i_l_e_n_a_m_e for reading.  If _f_i_l_e_n_a_m_e cannot be
  74.      opened or if memory for the LLDDFFIILLEE structure cannot be allocated, both
  75.      functions return NNUULLLL.  A successful open does not ensure that the
  76.      given file is a common object file or an archived object file.  When
  77.      calling llddooppeenn on a given aa..oouutt (rather than an archive) for the first
  78.      time be sure the second argument you pass is a NULL pointer [(LDFILE
  79.      *)0] (this is the only way to ensure the LLDDFFIILLEE ** is initialized
  80.      properly for that aa..oouutt file).
  81.  
  82.      llddrreeaaddsstt reads in the portions of the symbol table implied by the
  83.      _f_l_a_g_s argument.  A _f_l_a_g_s argument of --11 reads in the entire symbol
  84.      table.  Because the other routines, for example, llddttbbrreeaadd, ensure that
  85.      the relevant portions of the symbol table have been read in, you need
  86.      not call llddrreeaaddsstt to use the other routines.  llddrreeaaddsstt((llddppttrr,,--11)) would
  87.      simply ensure the whole symbol table is read in at once, which is not
  88.      necessary.  llddrreeaaddsstt returns SSUUCCCCEESSSS if it has read in the symbol
  89.      table successfully or FFAAIILLUURREE if it cannot.  If a symbol table has
  90.      been truncated or damaged, there is a small probability that llddrreeaaddsstt
  91.      will core dump rather than return FFAAIILLUURREE.
  92.  
  93.      llddooppeenn causes the symbol table header and file descriptor table to be
  94.      read.  Further access, using _l_d_p_t_r, causes other appropriate sections
  95.      of the symbol table to be read (for example, if you call llddttbbrreeaadd,, tthhee
  96.      ssyymmbboollss oorr eexxtteerrnnaallss aarree rreeaadd))..  TToo ffoorrccee sseeccttiioonnss ooff tthhee ssyymmbbooll ttaabbllee
  97.      iinnttoo mmeemmoorryy,, ccaallll llddrreeaaddsstt wwiitthh SSTT__PP** ccoonnssttaannttss OORReedd ttooggeetthheerr ffrroomm
  98.      <<ccmmppllrrss//ssttssuuppppoorrtt..hh>>..
  99.  
  100.      The program must be loaded with the object file access routine library
  101.      lliibbmmlldd..aa.
  102.  
  103.      The iinnttrroo(4) man page describes IINNCCDDIIRR and LLIIBBDDIIRR.
  104.  
  105. SSEEEE AALLSSOO
  106.      ffooppeenn(3S), llddcclloossee(3X)
  107.  
  108.      iinnttrroo(4), llddffccnn(4)
  109.  
  110.      This man page is available only online.
  111.